/*
 * @(#)Tour.java
 * 0.3 2011-12-22
 * 
 * Copyright (c) 2011 David Falk, Klaus Nicosia, Marcus Oberg.
 */
package logic;

/**
 * Interface for the Tour datatype for TSP.
 * 
 * @author      Klaus Nicosia,
 * @author      David Falk,
 * @author      Marcus Oberg.
 */
public interface Tour {
	
	/**
	 * Number of elements in the tour.
	 * 
	 * @return	the number of elements in the tour.
	 */
	int size();
	
	/**
	 * Length of the tour: the distance to travel.
	 * 
	 * @return	the length of the tour.
	 */
	int length();
	
	/**
	 * This is a query that returns the city that follows a in the current
	 * tour.
	 * 
	 * @param a	the vertex for which the next one is returned.
	 * @return	the next city.
	 */
	Vertex next(Vertex a);
	
	/**
	 * This is a query that returns the city that precedes a in the current
	 * tour.
	 * 
	 * @param a	the vertex for which the previous one is returned.
	 * @return	the previous city.
	 */
	Vertex prev(Vertex a);
	
	/**
	 * This is a query that returns true if b is found before c in a traversal
	 * from a.
	 * 
	 * @param a	the vertex where the traversal is started.
	 * @param b	the vertex to be found first for a true result.
	 * @param c	the vertex where the traversal ended if no b is found.
	 * @return	true if vertex b was found before c and false if not.
	 */
	boolean between(Vertex a, Vertex b, Vertex c);
	
	/**
	 * This updates the tour by replacing the edges (a, b) and (d, c) by the 
	 * edges (b, c) and (a, d). This operation assumes that b = Next(a) and 
	 * c = Next(d).
	 * 
	 * @param a	the first vertex in the first directed edge (a, b).
	 * @param b	the second vertex in the first directed edge (a, b).
	 * @param c	the second vertex in the second directed edge (d, c).
	 * @param d	the first vertex in the second directed edge (d, c).
	 */
	void flip(Vertex a, Vertex b, Vertex c, Vertex d);
		
	/**
	 * Returns the entire tour as an array of vertices.
	 * 
	 * @return	the tour as an array of vertices.
	 */
	Vertex[] getTour();
	
	/**
	 * Returns the entire tour represented as a String.
	 * 
	 * @return	the tour represented as a String.
	 */
	String toString();
	
	/**
	 * Returns the city at the specified index in the tour: the city to be
	 * visited as city number 'index'.
	 * 
	 * @param index	the index in the tour of the city to be returned.
	 * @return		the at the specified index in the tour.
	 */
	Vertex getCity(int index);
}
